AsyncAPI 3.x: publish a message's examples, some of the time - #1754

Why

A message's examples are what the document's author knows the service accepts. A service that silently drops what it does not recognise — the normal behaviour of a Kafka consumer or a WebSocket handler faced with a malformed message — may never reply to a payload sampled from the schema alone, and a search that never sees a reply never gets to tell the reply variants apart. Publishing the author's example some of the time is the cheapest way to make sure the search starts from something that works.

What it does

With --probAsyncApiExamples p (@Experimental, 0 by default), each example a message declares is offered as a whole payload beside the schema-derived genes, picked with probability p. A named example keeps its name, so probNamedExamples works for it as it does for REST. Headers examples are handled the same way, minus the correlation-id field the headers gene does not have either.

How

REST already builds a ChoiceGene between a caller-supplied list of named examples and the schema-derived genes, weighted by probUseExamples. createGeneForDTO takes that list as a trailing parameter, defaulted empty, and AsyncApiGeneBuilder passes every message example through it. The examples go beside the schema rather than into it because the OpenAPI 3.0 wrapper the genes are built through keeps only one example, drops names, and warns about one on a scalar.

Two details:

• Examples are dropped when probUseExamples is zero, as REST does, instead of building a choice weighted at zero.
• Built genes are cached by schema text, so a call with examples bypasses the cache: two messages can share a schema and differ in examples.

The TODO in AsyncApiSampler is removed.

Testing

AsyncApiGeneBuilderTest, AsyncApiSamplerTest and RestActionBuilderV3Test cover every example being offered, including on a scalar payload; a name reaching the action's named-example lookup; a headers example losing the correlation field; nothing changing shape at probability zero; and two messages sharing a schema keeping their own examples.

All AsyncAPI suites plus RestActionBuilderV3Test: 258 tests, 0 failures, 2 skipped.